Skip to content

Upgrade MUI to v5; replace material-table and react-swipeable-views#309

Open
ankit0504 wants to merge 16 commits intoLanguage-Mapping:masterfrom
ankit0504:agupta/upgrade-phase-4-mui-v5
Open

Upgrade MUI to v5; replace material-table and react-swipeable-views#309
ankit0504 wants to merge 16 commits intoLanguage-Mapping:masterfrom
ankit0504:agupta/upgrade-phase-4-mui-v5

Conversation

@ankit0504
Copy link
Copy Markdown
Collaborator

@ankit0504 ankit0504 commented Apr 28, 2026

Summary

Phase 4 of the dependency-upgrade series, stacked on #306 (phase 3, React 17). This is the big one:

  • MUI v4 → v5@material-ui/* packages renamed to @mui/*, Emotion installed as the styling engine, JSS-style makeStyles kept via the official @mui/styles shim so the 91 v4-style files don't all need rewriting.
  • material-table removed. It's unmaintained and never got a real MUI v5-compatible release. Replaced with @tanstack/react-table rendering MUI Table primitives.
  • react-swipeable-views removed. Was used in exactly one place. Replaced with plain MUI Tabs.

Why TanStack Table over the alternatives

The grid replacement was the biggest decision in this PR. Considered, in order:

Option Why ruled out
MUI X Data Grid v6 community Tried first. Multi-column filtering is paywalled — disableMultipleColumnsFiltering: true is hard-coded in community v6. With material-table users routinely set multiple per-column filters, single-column-only is a real regression.
MUI X Data Grid v5 community Free multi-column filtering, but last release was March 2023. v6/v7/v8 supersede it; v5 will not get fixes. Buys time, doesn't solve the problem.
MUI X Data Grid v7 / v8 Actively maintained but require React 18+. We're on React 17 (phase 3) and aren't doing the React 18 upgrade in this PR. Out of reach until a later phase.
MUI X Pro/Premium ~$15/dev/mo. Buys multi-column filtering plus features we don't need (column pinning, tree data, etc.). Not worth it for a community project.
material-table@2.0.6 Actually MUI v5 + React 17 compatible (overlooked in initial review). Smallest diff. But abandoned since 2022, still depends on the abandoned react-beautiful-dnd, and locks us out of React 18+. We'd just have to redo this migration in phase 5.
AG Grid Community Feature-rich and free, but ships its own design system (ag-theme-quartz) that won't match the rest of the MUI app without significant CSS work. Bundle is ~400kb.
TanStack Table v8 Headless (we render with MUI components ourselves), actively maintained, supports React 16/17/18+, no paywall now or later, no abandoned deps in the chain. Cost is a chunkier rewrite vs. Data Grid v5 — but it's a one-time cost that doesn't get re-spent at the next React/MUI bump.

Behavior changes vs. the old material-table

Preserved

  • Per-column filter row under the headers (text inputs, select dropdowns for Size/Status, "Has media" checkbox for Audio/Video)
  • Global search across visible columns
  • Sortable columns including the custom Size order (Smallest → Largest, not alphabetic)
  • Column show/hide menu
  • CSV and PDF export of the currently-filtered, currently-sorted, currently-visible rows
  • "View in map" and "Clear filters" buttons

Gone

  • "Click cell to filter by its value" — was implemented via material-table's imperative dataManager API. Could be re-added on top of TanStack with a custom onCellClick later if missed.
  • Sticky first/second columns. Material-table did this with absolute-positioned cells; we'd need similar custom CSS to bring it back.

Test plan

  • Search box filters across all columns
  • Per-column filter inputs work (Language, Endonym, Country, etc.)
  • Size sort goes Smallest → Largest, not alphabetic
  • Audio/Video checkboxes filter to rows that have a URL
  • Status / Size dropdowns show only the lookup options
  • Column visibility menu shows/hides columns; CSV and PDF reflect the visible set
  • PDF export opens with non-Roman scripts rendered correctly
  • "View in map" pushes the filtered set into the map and navigates home
  • Pagination + page-size selector work
  • Search tabs ("Search languages" / "Search locations") still toggle without the swipe gesture
  • Bottom nav, omnibox, dialog buttons, and breadcrumbs render fine with the v4→v5 styling shim

What's next

This is one in a sequence of upgrade phases. Roughly:

  • Phase 5react-router-dom 5 → 6, react-query v2 → TanStack Query v4, react-map-gl 5 → 7, replace the deprecated react-map-gl-geocoder. Library swaps only — stays on React 17.
  • Phase 6 — React 17 → 19 (skipping 18 as a destination since most projects pass through it on the way to 19), and TanStack Query v4 → v5 in the same PR since v5 requires React 18+.

We may split phase 6 if React 19 surfaces a lot of concurrent-rendering / StrictMode behavior changes during testing.

ankit0504 and others added 16 commits April 20, 2026 12:43
Replace react-scripts 3.4.1 with Vite 6 + @vitejs/plugin-react. This
drops the NODE_OPTIONS=--openssl-legacy-provider workaround required
for Node 17+ on CRA, and shrinks cold dev start to ~125ms and prod
build to ~5s (from ~33s).

Changes:
- Swap scripts: yarn start -> vite; yarn build -> tsc --noEmit &&
  vite build; yarn preview -> vite preview; drop eject/test.
- Replace CRA deps with vite, @vitejs/plugin-react, vite-plugin-svgr,
  vite-tsconfig-paths.
- Add vite.config.ts configuring the React and SVGR plugins, the
  REACT_APP_ env prefix (keeps .env working as-is, with VITE_ also
  accepted), port 3000, and build output to build/ (preserving the
  Netlify publish dir).
- Move public/index.html to project root. Replace %PUBLIC_URL%/ with
  / and add the Vite module entry script.
- Remove the CRA eslintConfig stanza in package.json; real config
  lives in .eslintrc.
- Add a direct eslint@^7.32.0 devDep (previously hoisted by CRA),
  drop the react-app extends that no longer resolves, and remove the
  deleted serviceWorker.ts path from ignorePatterns.
- Delete src/serviceWorker.ts and its import; it was already calling
  unregister() only, so removal is a no-op at runtime.
- Rewrite six process.env.REACT_APP_* reads as import.meta.env.
- Change Logo.tsx SVG import to use the vite-plugin-svgr ?react
  suffix.
- Update tsconfig.json: target ES2020, add vite/client and
  vite-plugin-svgr/client types, exclude *.test.ts/tsx files from
  the build since there is no test runner anymore.
- Delete src/setupTests.ts (orphaned CRA jest setup).

Known follow-ups (deliberately out of scope for this PR):
- @mapbox/mapbox-gl-geocoder imports the Node events module, which
  Vite externalizes for the browser. If the geocoder search breaks at
  runtime, it can be addressed by swapping react-map-gl-geocoder for
  a direct mapbox-gl-geocoder integration in a later phase.
- yarn lint surfaces 55 pre-existing errors across the codebase that
  were previously masked by CRA's react-app eslint preset. These are
  unrelated to the build migration and should be addressed in a
  follow-up. Pre-commit lint-staged only runs against staged files,
  so new commits are unaffected.
Removing react-scripts in the previous commit unmasked pre-existing
eslint errors that CRA's react-app preset had been silencing.

Cleanup by category:
- 40 @typescript-eslint/no-unused-vars: set { args: "none" } in the
  rule config. These were all unused callback parameters (mostly
  createStyles theme args and event/props args in handlers) required
  by library type signatures. The project-level policy is to not
  enforce unused function arguments; genuine unused variables and
  imports are still checked.
- 5 @typescript-eslint/no-use-before-define: reorder the five helper
  function definitions so each precedes its call site. Affected:
  createLayerStyles (hooks.points.ts), handleClose (SplitCrumbs.tsx),
  scrollToTop (ResultsTable.tsx), clearFiltersBtnClick
  (ResultsToolbar.tsx), excludeUTFtext (exporting.ts).
- 6 jsx-a11y/anchor-is-valid: five MUI <Link> usages that are
  semantically buttons now use component="button" and drop the dummy
  href="#" plus its e.preventDefault() plumbing. The sixth
  (MapOptionsMenu) already uses component={Button}. All six get an
  eslint-disable-next-line comment because the rule inspects JSX
  element names and doesn't analyze MUI's component prop -- the
  markup is correct, the rule is a false positive.
- 3 parser errors in excluded test files: add src/**/*.test.ts(x) to
  .eslintrc ignorePatterns. The tsconfig already excludes these from
  the build.
The airtable package references process.env at runtime, which
webpack/CRA provided but Vite does not. Defining an empty object
prevents the ReferenceError without leaking server-side env vars.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Rename vite.config.ts to vite.config.mts for ESM compatibility
- Replace MUI Link-as-button with Button in 6 components
- Pass Airtable API key explicitly instead of relying on process.env
- Migrate remaining process.env reference to import.meta.env

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Bump react/react-dom to 17.0.2 and @types/react/@types/react-dom to
the latest 17.x. Also bump @types/react-router-dom to 5.3.3 (5.1.5
was typed against React 16 and triggered TS2786 'cannot be used as
a JSX component' errors for RouterLink passed to MUI component
props).

Add @types/react and @types/react-dom to the resolutions field so
that transitively-installed type packages (eight of them — MUI,
react-map-gl, react-swipeable-views, etc. all vendored their own
@types/react@16) do not conflict with the top-level version. Without
this, tsc sees multiple React type identities and cannot reconcile
JSX element returns across package boundaries.

React 17 has no API surface changes that affect this project, so no
component code changes are required. React 18 is intentionally
deferred to a later phase, after MUI v5 lands — react-swipeable-views
is archived and breaks in React 18 StrictMode, and MUI v4 has React
18 peer-dep conflicts.

Known-ignorable peer-dep warnings on install: react-query@2,
react-share@4, react-swipeable-views, react-window, and
react-router-dom all still declare React 16 as their max in their
peer range, but each of them works with React 17 in practice.
Mechanical rename of @material-ui/core, @material-ui/lab, and
@material-ui/styles imports to their @mui/* equivalents. Adds Emotion
(MUI v5's default styling engine) and keeps @mui/styles as a JSS shim
so the existing makeStyles/withStyles call sites keep working.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
react-swipeable-views was used in exactly one place (SearchTabs.tsx)
to wrap two TabPanel children. Removed the swipe affordance and let
TabPanel's existing index/value gating handle which pane is shown.
The library is unmaintained and incompatible with React 17+.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
material-table is unmaintained and incompatible with MUI v5. Swap it
for @mui/x-data-grid (community) which covers filtering, sorting,
column visibility, pagination, and quick filter out of the box.

Notable behavior changes:
- The "click cell to filter by its value" interaction is dropped. It
  was implemented via material-table's imperative dataManager API and
  has no clean Data Grid equivalent. Filters are now driven by the
  built-in column filter UI plus the quick-filter search box.
- The MediaColumnFilter checkbox is reimplemented as a custom
  GridFilterOperator on the Audio/Video columns.
- Custom CSV/PDF export buttons (exporting.ts) are no longer wired up
  in the toolbar. CSV is available via the column menu; if PDF export
  is still needed it can be re-added as a slot button later.
- Sticky first/second columns are dropped — Data Grid pinning is a
  Pro feature and the actions columns work fine without it.

Move clsx, filefy, history, jspdf, jspdf-autotable, and mapbox-gl
from peerDependencies (where yarn auto-installed them) into regular
dependencies. With material-table removed they're no longer pulled
transitively.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The codemod handles renames but leaves several v5 API changes for
manual cleanup:

- theme: replace post-creation `customTheme.overrides = {...}` with
  the v5 `components: { ComponentName: { styleOverrides: {...} } }`
  shape passed into a second createTheme call.
- ProvidersWrap: import Theme/StyledEngineProvider from
  @mui/material/styles (not @mui/styles, which no longer re-exports
  them in v5).
- palette.text.hint is removed in v5 — swap to palette.text.disabled.
- Autocomplete renderOption: new signature receives (props, option),
  so wrap children in <li {...props}>.
- BottomNavigationAction: drop the `wrapper` and `label` class slots
  (no longer part of the component's classes shape).
- Fab: drop the `label` class slot and inline its sizing on root.
- TimelineDot: variant `'default'` is gone, use `'filled'`.
- ToggleButton: remove non-standard `color="blue"`; the default works.
- Slide TransitionComponent: children must be required, not optional.
- Demo files: minor typing fixes for ClickAwayListener and Select
  onChange handlers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ns buttons

The previous commit dropped the export buttons because Data Grid
doesn't expose a custom format hook the way material-table did, but
the existing exporting.ts utilities still work — they just need to
be called with the currently-visible rows from apiRef. Pass the
column config through slot props.

Also surface Data Grid's built-in Filters and Columns toggles in the
toolbar. They were technically reachable through each column's
hover-only menu, which was hard to find.

Inline the localIndicator styles in LocalColumnTitle to avoid an
import cycle (config -> LocalColumnTitle -> ResultsToolbar -> exporting
-> config) introduced by the toolbar now needing exporting.ts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Data Grid uses a fixed row height by default. Cells with multiple
values per row (Country with two flags, Endonym wrapping non-Latin
scripts, etc.) were getting clipped and bleeding into adjacent rows.
Setting getRowHeight to 'auto' lets each row grow to fit its
tallest cell; getEstimatedRowHeight keeps virtualization fast on
the 1000+ row dataset. Cell content is top-aligned so single-line
columns line up cleanly with multi-line ones.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The MediaFilterInput rendered the checkbox too high because the
default FormControlLabel doesn't share Data Grid's filter input
baseline. Bottom-align it and pull the original 'http' marker color
in via the secondary palette so the checkbox tone matches the other
filter controls.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Data Grid's free tier (community v6) hard-codes
disableMultipleColumnsFiltering: true, so users could only filter
on one column at a time. Multi-column filtering is paywalled to the
Pro plan in v6, and v5 — the last version that had it free — was
last released March 2023 and is no longer maintained.

TanStack Table v8 is headless and actively maintained, supports
React 16/17/18+, and its filter model has no paywall. The trade-off
is that we render the table primitives ourselves with MUI Table /
TableHead / TableBody, which lets us bring back material-table's
per-column filter row UX (text input by default, Select for lookup
columns, the Has-media checkbox for Audio/Video).

Other features carried over:
- Global search box (matches across visible columns)
- Column visibility menu in the toolbar
- CSV / PDF export wired to filtered+sorted rows
- "View in map" and "Clear filters" buttons unchanged

Column config moved to TanStack column defs via createColumnHelper.
Cell renderers now receive a CellContext and read row.original;
filter logic for Audio/Video lives in mediaUrlFilterFn.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
React throws when a function passed to flexRender returns undefined.
Several columns (Glottocode, ISO 639-3, Additional Neighborhoods,
Endonym, etc.) are nullable in the dataset, and their default cell
renderers were `info.getValue()` — which returns undefined for any
row where the field is missing.

Coerce all simple-text cells with ?? '' and add a guard in
renderCountryColumn / renderEndoColumn for rows without those fields.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The column header already says "Audio" / "Video"; the checkbox in
the filter row beneath it is unambiguous. Replace the labelled
FormControlLabel with a bare Checkbox and put the explanatory text
in the title attribute for hover discoverability.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The toolbar was passing the static column config to exportCsv/exportPdf
regardless of which columns the user had hidden via the column
visibility menu. Filter the config by columnVisibility before handing
it to the export utilities so a downloaded CSV/PDF reflects exactly
what's on screen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant